package com.kehutong.wxapi.service;

import com.kehutong.wxapi.request.*;
import com.kehutong.wxapi.response.*;
import com.kehutong.wxapi.service.impl.ExternalContactServiceImpl;
import org.coraframework.inject.ImplementedBy;

/**
 * 客户管理服务类
 */
@ImplementedBy(ExternalContactServiceImpl.class)
public interface ExternalContactService {

    /**
     * 获取配置了客户联系功能的成员列表
     * 企业和第三方服务商可通过此接口获取配置了客户联系功能的成员列表。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_follow_user_list?access_token=ACCESS_TOKEN
     * @param followUserListRequest 配置了客户联系功能的成员列表请求对象
     * @return 配置了客户联系功能的成员列表响应对象
     * @throws Exception 异常
     */
     FollowUserListResponse getFollowUserList(FollowUserListRequest followUserListRequest) throws Exception;

    /**
     *获取客户列表(没有客户的信息信息只有标志)
     * 企业可通过此接口获取指定成员添加的客户列表。客户是指配置了客户联系功能的成员所添加的外部联系人。没有配置客户联系功能的成员，所添加的外部联系人将不会作为客户返回。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/list?access_token=ACCESS_TOKEN&userid=USERID
     * @param externalContactListRequest 客户列表请求对象
     * @return 客户列表返回对象
     * @throws Exception 异常
     */
    ExternalContactListResponse getExternalContactList(ExternalContactListRequest externalContactListRequest) throws Exception;

    /**
     * 获取客户详情
     * 企业可通过此接口，根据外部联系人的userid（如何获取?），拉取客户详情。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get?access_token=ACCESS_TOKEN&external_userid=EXTERNAL_USERID&cursor=CURSOR
     * @param externalContactGetRequest 客户详情请求对象
     * @return 客户详情响应对象
     * @throws Exception 异常
     */
    ExternalContactGetResponse getExternalContact(ExternalContactGetRequest externalContactGetRequest) throws Exception;


    /**
     * 批量获取客户详情
     * 企业/第三方可通过此接口获取指定成员(员工)添加的客户详细信息列表。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/batch/get_by_user?access_token=ACCESS_TOKEN
     * @param batchGetByUserRequest 批量获取客户详情请求对象
     * @return 批量获取客户详情响应对象
     * @throws Exception 异常
     */
    BatchGetByUserResponse batchGetByUser(BatchGetByUserRequest batchGetByUserRequest) throws Exception;


    /**
     * 修改客户备注信息
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/remark?access_token=ACCESS_TOKEN
     * @param externalContactRemarkUpdateRequest 修改客户备注信息请求对象
     * @return 修改客户备注信息响应对象
     * @throws Exception 异常
     */
    ExternalContactRemarkUpdateResponse updateExternalContactRemark(ExternalContactRemarkUpdateRequest externalContactRemarkUpdateRequest) throws Exception;


    /**
     * 获取企业标签库
     * 企业可通过此接口获取企业客户标签详情。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_corp_tag_list?access_token=ACCESS_TOKEN
     * @param corpTagListRequest 企业标签库请求对象
     * @return 企业标签库响应对象
     * @throws Exception 异常
     */
    CorpTagListResponse getCorpTagList(CorpTagListRequest corpTagListRequest) throws Exception;

    /**
     * 添加企业客户标签
     * 企业可通过此接口向客户标签库中添加新的标签组和标签，每个企业最多可配置3000个企业标签。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_corp_tag?access_token=ACCESS_TOKEN
     * @param corpTagAddRequest 添加企业客户标签请求对象
     * @return 添加企业客户标签响应对象
     * @throws Exception 异常
     */
    CorpTagAddResponse addCorpTag(CorpTagAddRequest corpTagAddRequest) throws Exception;

    /**
     * 编辑企业客户标签
     * 企业可通过此接口向客户标签库中添加新的标签组和标签，每个企业最多可配置3000个企业标签。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/edit_corp_tag?access_token=ACCESS_TOKEN
     * @param corpTagEditRequest 编辑企业客户标签请求对象
     * @return 编辑企业客户标签响应对象
     * @throws Exception 异常
     */
    CorpTagEditResponse editCorpTag(CorpTagEditRequest corpTagEditRequest) throws Exception;

    /**
     * 删除企业客户标签
     * 企业可通过此接口删除客户标签库中的标签，或删除整个标签组。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/del_corp_tag?access_token=ACCESS_TOKEN
     * @param corpTagDeleteRequest 删除企业客户标签请求对象
     * @return 删除企业客户标签响应对象
     * @throws Exception 异常
     */
    CorpTagDeleteResponse deleteCorpTag(CorpTagDeleteRequest corpTagDeleteRequest) throws Exception;

    /**
     * 编辑客户企业标签
     * 企业可通过此接口为指定成员的客户添加上由企业统一配置的标签。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/mark_tag?access_token=ACCESS_TOKEN
     * @param markTagRequest 编辑客户企业标签请求对象
     * @return 编辑客户企业标签响应对象
     * @throws Exception 异常
     */
    MarkTagResponse markTag(MarkTagRequest markTagRequest) throws Exception;

    /**
     * 分配在职成员的客户
     * 企业可通过此接口，转接在职成员的客户给其他成员。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/transfer_customer?access_token=ACCESS_TOKEN
     * @param transferCustomerRequest 分配在职成员的客户请求对象
     * @return 分配在职成员的客户响应对象
     * @throws Exception 异常
     */
    TransferCustomerResponse transferCustomer(TransferCustomerRequest transferCustomerRequest) throws Exception;

    /**
     * 查询客户接替状态
     * 企业和第三方可通过此接口查询在职成员的客户转接情况。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/transfer_result?access_token=ACCESS_TOKEN
     * @param transferResultRequest 查询客户接替状态请求对象
     * @return 查询客户接替状态响应对象
     * @throws Exception 异常
     */
    TransferResultResponse transferResult(TransferResultRequest transferResultRequest) throws Exception;


    /**
     * 获取待分配的离职成员列表
     * 企业和第三方可通过此接口，获取所有离职成员的客户列表，并可进一步调用分配离职成员的客户接口将这些客户重新分配给其他企业成员。
     * https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_unassigned_list?access_token=ACCESS_TOKEN
     * @param getUnassignedListRequest 获取待分配的离职成员列表请求对象
     * @return 获取待分配的离职成员列表响应对象
     * @throws Exception 异常
     */
    GetUnassignedListResponse getUnassignedList(GetUnassignedListRequest getUnassignedListRequest) throws Exception;


    /**
     * 分配离职成员的客户
     * 企业可通过此接口，分配离职成员的客户给其他成员
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/resigned/transfer_customer?access_token=ACCESS_TOKEN
     * @param resignedTransferCustomerRequest 分配离职成员的客户请求对象
     * @return 分配离职成员的客户响应对象
     * @throws Exception 异常
     */
    ResignedTransferCustomerResponse resignedTransferCustomer(ResignedTransferCustomerRequest resignedTransferCustomerRequest) throws Exception;


    /**
     * 查询离职客户接替状态
     * 企业和第三方可通过此接口查询离职成员的客户分配情况。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/resigned/transfer_result?access_token=ACCESS_TOKEN
     * @param resignedTransferResultRequest 查询离职客户接替状态请求对象
     * @return 查询离职客户接替状态响应对象
     * @throws Exception 异常
     */
    ResignedTransferResultResponse resignedTransferResult(ResignedTransferResultRequest resignedTransferResultRequest) throws Exception;


    /**
     * 分配离职成员的客户群
     * 企业可通过此接口，将已离职成员为群主的群，分配给另一个客服成员。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/transfer?access_token=ACCESS_TOKEN
     * @param groupChatTransferRequest 分配离职成员的客户群请求对象
     * @return 分配离职成员的客户群响应对象
     * @throws Exception 异常
     */
    GroupChatTransferResponse groupChatTransfer(GroupChatTransferRequest groupChatTransferRequest) throws Exception;

    /**
     * 获取客户群列表
     * 该接口用于获取配置过客户群管理的客户群列表。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/list?access_token=ACCESS_TOKEN
     * @param groupChatListRequest 获取客户群列表请求对象
     * @return 获取客户群列表响应对象
     * @throws Exception 异常
     */
    GroupChatListResponse groupChatList(GroupChatListRequest groupChatListRequest) throws Exception;


    /**
     * 获取客户群详情
     * 通过客户群ID，获取详情。包括群名、群成员列表、群成员入群时间、入群方式。（客户群是由具有客户群使用权限的成员创建的外部群）
     * 需注意的是，如果发生群信息变动，会立即收到群变更事件，但是部分信息是异步处理，可能需要等一段时间调此接口才能得到最新结果
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/get?access_token=ACCESS_TOKEN
     * @param groupChatGetRequest 获取客户群详情请求对象
     * @return 获取客户群详情响应对象
     * @throws Exception 异常
     */
    GroupChatGetResponse groupChatGet(GroupChatGetRequest groupChatGetRequest) throws Exception;

    /**
     * 企业和第三方应用可通过该接口获取企业全部的发表内容。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_moment_list?access_token=ACCESS_TOKEN
     * @param getMomentListRequest 企业和第三方应用可通过该接口获取企业全部的发表内容请求对象
     * @return 企业和第三方应用可通过该接口获取企业全部的发表内容。响应对象
     * @throws Exception 异常
     */
    GetMomentListResponse getMomentList(GetMomentListRequest getMomentListRequest) throws Exception;

    /**
     * 企业和第三方应用可通过该接口获取企业发表的朋友圈成员执行情况
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_moment_task?access_token=ACCESS_TOKEN
     * @param getMomentTaskRequest 企业和第三方应用可通过该接口获取企业发表的朋友圈成员执行情况请求对象
     * @return 企业和第三方应用可通过该接口获取企业发表的朋友圈成员执行情况响应对象
     * @throws Exception 异常
     */
    GetMomentTaskResponse getMomentTask(GetMomentTaskRequest getMomentTaskRequest) throws Exception;

    /**
     * 获取客户朋友圈发表时选择的可见范围
     * 企业和第三方应用可通过该接口获取客户朋友圈创建时，选择的客户可见范围
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_moment_customer_list?access_token=ACCESS_TOKEN
     * @param getMomentCustomerListRequest 获取客户朋友圈发表时选择的可见范围请求对象
     * @return 获取客户朋友圈发表时选择的可见范围响应对象
     * @throws Exception 异常
     */
    GetMomentCustomerListResponse getMomentCustomerList(GetMomentCustomerListRequest getMomentCustomerListRequest) throws Exception;


    /**
     * 获取客户朋友圈发表后的可见客户列表
     * 企业和第三方应用可通过该接口获取客户朋友圈发表后，可在微信朋友圈中查看的客户列表
     * 请求地址：请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_moment_send_result?access_token=ACCESS_TOKEN
     * @param getMomentSendResultRequest 获取客户朋友圈发表后的可见客户列表请求对象
     * @return 获取客户朋友圈发表后的可见客户列表响应对象
     * @throws Exception 异常
     */
    GetMomentSendResultResponse getMomentSendResult(GetMomentSendResultRequest getMomentSendResultRequest) throws Exception;

    /**
     * 获取客户朋友圈的互动数据
     * 企业和第三方应用可通过此接口获取客户朋友圈的互动数据。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_moment_comments?access_token=ACCESS_TOKEN
     * @param getMomentCommentsRequest 获取客户朋友圈的互动数据请求对象
     * @return 获取客户朋友圈的互动数据响应对象
     * @throws Exception 异常
     */
    GetMomentCommentsResponse getMomentComments(GetMomentCommentsRequest getMomentCommentsRequest) throws Exception;


    /**
     * 创建企业群发
     * 企业跟第三方应用可通过此接口添加企业群发消息的任务并通知成员发送给相关客户或客户群。（注：企业微信终端需升级到2.7.5版本及以上）
     * 注意：调用该接口并不会直接发送消息给客户/客户群，需要成员确认后才会执行发送（客服人员的企业微信需要升级到2.7.5及以上版本）
     * 同一个企业每个自然月内仅可针对一个客户/客户群发送4条消息，超过接收上限的客户将无法再收到群发消息。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_msg_template?access_token=ACCESS_TOKEN
     * @param addMsgTemplateRequest 创建企业群发数据请求对象
     * @return 创建企业群发数据响应对象
     * @throws Exception 异常
     */
    AddMsgTemplateResponse addMsgTemplate(AddMsgTemplateRequest addMsgTemplateRequest) throws Exception;

    /**
     * 企业和第三方应用可通过此接口获取企业与成员的群发记录。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_groupmsg_list?access_token=ACCESS_TOKEN
     * @param getGroupMsgListRequest 获取群发记录列表请求对象
     * @return 获取群发记录列表响应对象
     * @throws Exception 异常
     */
    GetGroupMsgListResponse getGroupMsgList(GetGroupMsgListRequest getGroupMsgListRequest) throws Exception;

    /**
     * 获取群发成员发送任务列表
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_groupmsg_task?access_token=ACCESS_TOKEN
     * @param getGroupMsgTaskRequest 获取群发成员发送任务列表请求对象
     * @return 获取群发成员发送任务列表响应对象
     * @throws Exception 异常
     */
    GetGroupMsgTaskResponse getGroupMsgTask(GetGroupMsgTaskRequest getGroupMsgTaskRequest) throws Exception;

    /**
     * 获取企业群发成员执行结果
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_groupmsg_send_result?access_token=ACCESS_TOKEN
     * @param getGroupMsgSendResultRequest 获取企业群发成员执行结果请求对象
     * @return 获取企业群发成员执行结果响应对象
     * @throws Exception 异常
     */
    GetGroupMsgSendResultResponse getGroupMsgSendResult(GetGroupMsgSendResultRequest getGroupMsgSendResultRequest) throws Exception;

    /**
     * 发送新客户欢迎语
     * 企业微信在向企业推送添加外部联系人事件时，会额外返回一个welcome_code，企业以此为凭据调用接口，即可通过成员向新添加的客户发送个性化的欢迎语。
     * 为了保证用户体验以及避免滥用，企业仅可在收到相关事件后20秒内调用，且只可调用一次。
     * 如果企业已经在管理端为相关成员配置了可用的欢迎语，则推送添加外部联系人事件时不会返回welcome_code。
     * 每次添加新客户时可能有多个企业自建应用/第三方应用收到带有welcome_code的回调事件，但仅有最先调用的可以发送成功。后续调用将返回41051（externaluser has started chatting）错误，请用户根据实际使用需求，合理设置应用可见范围，避免冲突。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/send_welcome_msg?access_token=ACCESS_TOKEN
     * @param sendWelcomeMsgRequest 发送新客户欢迎语请求对象
     * @return 发送新客户欢迎语响应对象
     * @throws Exception 异常
     */
    SendWelcomeMsgResponse sendWelcomeMsg(SendWelcomeMsgRequest sendWelcomeMsgRequest) throws Exception;

    /**
     * 添加入群欢迎语素材
     * 企业可通过此API向企业的入群欢迎语素材库中添加素材。每个企业的入群欢迎语素材库中，最多容纳100个素材。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/group_welcome_template/add?access_token=ACCESS_TOKEN
     * @param groupWelcomeTemplateAddRequest 添加入群欢迎语素材请求对象
     * @return 添加入群欢迎语素材响应对象
     * @throws Exception 异常
     */
    GroupWelcomeTemplateAddResponse groupWelcomeTemplateAdd(GroupWelcomeTemplateAddRequest groupWelcomeTemplateAddRequest) throws Exception;

    /**
     * 编辑入群欢迎语素材
     * 企业可通过此API编辑入群欢迎语素材库中的素材，且仅能够编辑调用方自己创建的入群欢迎语素材。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/group_welcome_template/edit?access_token=ACCESS_TOKEN
     * @param groupWelcomeTemplateEditRequest 编辑入群欢迎语素材请求对象
     * @return 编辑入群欢迎语素材响应对象
     * @throws Exception 异常
     */
    GroupWelcomeTemplateEditResponse groupWelcomeTemplateEdit(GroupWelcomeTemplateEditRequest groupWelcomeTemplateEditRequest) throws Exception;


    /**
     * 获取入群欢迎语素材
     * 企业可通过此API获取入群欢迎语素材。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/group_welcome_template/get?access_token=ACCESS_TOKEN
     * @param groupWelcomeTemplateGetRequest 获取入群欢迎语素材请求对象
     * @return 获取入群欢迎语素材响应对象
     * @throws Exception 异常
     */
    GroupWelcomeTemplateGetResponse groupWelcomeTemplateGet(GroupWelcomeTemplateGetRequest groupWelcomeTemplateGetRequest) throws Exception;


    /**
     * 删除入群欢迎语素材
     * 企业可通过此API删除入群欢迎语素材，且仅能删除调用方自己创建的入群欢迎语素材
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/group_welcome_template/del?access_token=ACCESS_TOKEN
     * @param groupWelcomeTemplateDelRequest 删除入群欢迎语素材请求对象
     * @return 删除入群欢迎语素材响应对象
     * @throws Exception 异常
     */
    GroupWelcomeTemplateDelResponse groupWelcomeTemplateGet(GroupWelcomeTemplateDelRequest groupWelcomeTemplateDelRequest) throws Exception;


    /**
     * 获取「联系客户统计」数据
     * 企业可通过此接口获取成员联系客户的数据，包括发起申请数、新增客户数、聊天数、发送消息数和删除/拉黑成员的客户数等指标。
     * 请求地址:https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get_user_behavior_data?access_token=ACCESS_TOKEN
     * @param getUserBehaviorDataRequest 获取「联系客户统计」数据请求对象
     * @return 获取「联系客户统计」数据响应对象
     * @throws Exception 异常
     */
    GetUserBehaviorDataResponse getUserBehaviorData(GetUserBehaviorDataRequest getUserBehaviorDataRequest) throws Exception;


    /**
     * 获取「群聊数据统计」数据按群主聚合的方式
     * 获取指定日期的统计数据。注意，企业微信仅存储180天的数据。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/statistic?access_token=ACCESS_TOKEN
     * @param groupChatStatisticRequest 获取「群聊数据统计」数据按群主聚合的方式请求对象
     * @return 获取「群聊数据统计」数据按群主聚合的方式响应对象
     * @throws Exception 异常
     */
    GroupChatStatisticResponse groupChatStatistic(GroupChatStatisticRequest groupChatStatisticRequest) throws Exception;


    /**
     * 获取「群聊数据统计」数据按自然日聚合的方式
     * 获取指定日期的统计数据。注意，企业微信仅存储180天的数据。
     * 请求地址：https://qyapi.weixin.qq.com/cgi-bin/externalcontact/groupchat/statistic_group_by_day?access_token=ACCESS_TOKEN
     * @param groupChatStatisticGroupByDayRequest 获取「群聊数据统计」数据按自然日聚合的方式请求对象
     * @return 获取「群聊数据统计」数据按自然日聚合的方式响应对象
     * @throws Exception 异常
     */
    GroupChatStatisticGroupByDayResponse groupChatStatisticGroupByDay(GroupChatStatisticGroupByDayRequest groupChatStatisticGroupByDayRequest) throws Exception;
}
